docs: align OpenAPI spec with content API implementation#120
Merged
sweetmantech merged 3 commits intomainfrom Apr 9, 2026
Merged
docs: align OpenAPI spec with content API implementation#120sweetmantech merged 3 commits intomainfrom
sweetmantech merged 3 commits intomainfrom
Conversation
📝 WalkthroughWalkthroughThe OpenAPI schema for the content API was updated across multiple endpoints: audio response field renamed from Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
api-reference/openapi.json (2)
14893-14903:⚠️ Potential issue | 🟠 MajorRemove image input from the PATCH endpoint description too.
The schema now says edits require
video_urloraudio_url, but Line 4066 still says the endpoint accepts image input. The spec is still self-contradictory for consumers reading the path docs first.Suggested fix
- "description": "Apply edits to content — trim, crop, resize, overlay text, or add an audio track. Accepts video, image, or audio input. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.", + "description": "Apply edits to content — trim, crop, resize, overlay text, or add an audio track. Accepts video or audio input. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 14893 - 14903, The PATCH endpoint documentation currently contradicts the schema by still mentioning image input; update the PATCH operation description text to remove any reference to image input and explicitly state that only video_url or audio_url are accepted (matching the schema properties video_url and audio_url), ensuring the path-level description and any examples or parameters no longer reference image input so the docs and the schema are consistent.
14652-14679:⚠️ Potential issue | 🟠 MajorThe video docs still advertise a text-only mode.
After Line 14652 makes
image_urlmandatory, the path description at Line 5872 is misleading because it still sayspromptcreates a video from text alone. That will send readers down a broken path.Suggested fix
- "description": "Generate a video. Set `mode` to control what kind of video you get:\n\n- `prompt` — create a video from a text description\n- `animate` — animate a still image\n- `reference` — use an image as a style/subject reference (not the first frame)\n- `extend` — continue an existing video\n- `first-last` — generate a video that transitions between two images\n- `lipsync` — sync face movement to an audio clip\n\nIf `mode` is omitted, it's inferred from the inputs you provide.", + "description": "Generate a video from an input image. Set `mode` to control how that image is used:\n\n- `prompt` — use the prompt to guide an image-driven video\n- `animate` — animate a still image\n- `reference` — use an image as a style/subject reference (not the first frame)\n- `extend` — continue an existing video\n- `first-last` — generate a video that transitions between two images\n- `lipsync` — sync face movement to an audio clip\n\nText-only prompt mode is not supported. If `mode` is omitted, it's inferred from the inputs you provide.",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 14652 - 14679, The OpenAPI docs still imply a text-only "prompt" mode even though the request schema now requires image_url; update the endpoint description/media docs that reference the "prompt" mode (and any examples) to state that image_url is required and that text-only generation is not supported: adjust the textual description for the video generation operation to mention the required property image_url, remove or revise any sentences claiming prompt can create a video from text alone, and ensure the mode enum description and sample request bodies reflect that callers must supply image_url (and that prompt only augments motion/content when an image is provided).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 14622-14624: The OpenAPI schema for the "model" property currently
only documents the default in the description; update the schema for the "model"
property in api-reference/openapi.json to include a JSON Schema "default":
"fal-ai/nano-banana-2" alongside the existing "type" and "description" so
generated docs/clients surface the actual default value for the model field.
- Around line 14864-14872: The schema rename from songUrl to audioUrl is
incomplete: update the OpenAPI schema for the "audioUrl" property to declare it
as a URI (keep "type": "string" but add "format": "uri" and ensure the
description references "audioUrl" as the URL of the transcribed audio), and
search the document for the legacy success message "Song transcribed
successfully." and change it to a matching phrase such as "Audio transcribed
successfully." Also sweep for any remaining occurrences of the old property name
"songUrl" and replace them with "audioUrl" (including examples, response
examples, and descriptions) so the rename is consistent across the OpenAPI spec.
- Around line 14631-14646: The response schema for the image-generation model
still allows empty/unbounded arrays and the endpoint description is outdated;
add "minItems": 1 and "maxItems": 4 to the "images" property in the schema (next
to the existing "type":"array" and "items") so the array is constrained to 1..4,
keep "imageUrl" as the first generated image but ensure its description matches
the multi-image contract, and update the endpoint path description that
currently says "Returns the image URL." to reflect that the endpoint returns one
or more image URLs (up to 4) so the spec is consistent.
---
Outside diff comments:
In `@api-reference/openapi.json`:
- Around line 14893-14903: The PATCH endpoint documentation currently
contradicts the schema by still mentioning image input; update the PATCH
operation description text to remove any reference to image input and explicitly
state that only video_url or audio_url are accepted (matching the schema
properties video_url and audio_url), ensuring the path-level description and any
examples or parameters no longer reference image input so the docs and the
schema are consistent.
- Around line 14652-14679: The OpenAPI docs still imply a text-only "prompt"
mode even though the request schema now requires image_url; update the endpoint
description/media docs that reference the "prompt" mode (and any examples) to
state that image_url is required and that text-only generation is not supported:
adjust the textual description for the video generation operation to mention the
required property image_url, remove or revise any sentences claiming prompt can
create a video from text alone, and ensure the mode enum description and sample
request bodies reflect that callers must supply image_url (and that prompt only
augments motion/content when an image is provided).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7c3226f3-e154-4013-8072-6e0b434bc463
📒 Files selected for processing (1)
api-reference/openapi.json
api-reference/openapi.json
Outdated
Comment on lines
+14622
to
+14624
| "model": { | ||
| "type": "string", | ||
| "description": "fal.ai model ID. Defaults to fal-ai/nano-banana-pro/edit" | ||
| "description": "fal.ai model ID. Defaults to fal-ai/nano-banana-2" |
There was a problem hiding this comment.
Expose the default image model as schema data.
Line 14624 only mentions the default in prose. Without a default value, generated docs and clients won't surface fal-ai/nano-banana-2 as the actual default.
Suggested fix
"model": {
"type": "string",
+ "default": "fal-ai/nano-banana-2",
"description": "fal.ai model ID. Defaults to fal-ai/nano-banana-2"
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "model": { | |
| "type": "string", | |
| "description": "fal.ai model ID. Defaults to fal-ai/nano-banana-pro/edit" | |
| "description": "fal.ai model ID. Defaults to fal-ai/nano-banana-2" | |
| "model": { | |
| "type": "string", | |
| "default": "fal-ai/nano-banana-2", | |
| "description": "fal.ai model ID. Defaults to fal-ai/nano-banana-2" | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 14622 - 14624, The OpenAPI schema
for the "model" property currently only documents the default in the
description; update the schema for the "model" property in
api-reference/openapi.json to include a JSON Schema "default":
"fal-ai/nano-banana-2" alongside the existing "type" and "description" so
generated docs/clients surface the actual default value for the model field.
api-reference/openapi.json
Outdated
Comment on lines
+14631
to
+14646
| "imageUrl", | ||
| "images" | ||
| ], | ||
| "properties": { | ||
| "imageUrl": { | ||
| "type": "string", | ||
| "format": "uri", | ||
| "description": "URL of the generated image" | ||
| "description": "URL of the first generated image" | ||
| }, | ||
| "images": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string", | ||
| "format": "uri" | ||
| }, | ||
| "description": "URLs of all generated images. Contains one element when num_images is 1." |
There was a problem hiding this comment.
Finish the multi-image response contract.
The schema now returns images, but it still allows an empty or unbounded array, and Line 5806 still says the endpoint “Returns the image URL.” Tighten the array bounds to 1..4 and update the path description so the spec stays internally consistent.
Suggested fix
- "description": "Generate an image from a text prompt. Pass a `reference_image_url` to guide the output toward a specific look or subject. Returns the image URL.",
+ "description": "Generate one or more images from a text prompt. Pass a `reference_image_url` to guide the output toward a specific look or subject. Returns `imageUrl` for the first image and `images` for the full set.",
...
"images": {
"type": "array",
+ "minItems": 1,
+ "maxItems": 4,
"items": {
"type": "string",
"format": "uri"
},🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 14631 - 14646, The response schema
for the image-generation model still allows empty/unbounded arrays and the
endpoint description is outdated; add "minItems": 1 and "maxItems": 4 to the
"images" property in the schema (next to the existing "type":"array" and
"items") so the array is constrained to 1..4, keep "imageUrl" as the first
generated image but ensure its description matches the multi-image contract, and
update the endpoint path description that currently says "Returns the image
URL." to reflect that the endpoint returns one or more image URLs (up to 4) so
the spec is consistent.
api-reference/openapi.json
Outdated
Comment on lines
+14864
to
+14872
| "audioUrl", | ||
| "fullLyrics", | ||
| "segments", | ||
| "segmentCount" | ||
| ], | ||
| "properties": { | ||
| "songUrl": { | ||
| "audioUrl": { | ||
| "type": "string", | ||
| "description": "URL of the transcribed song" | ||
| "description": "URL of the transcribed audio" |
There was a problem hiding this comment.
Complete the songUrl → audioUrl rename.
Line 14870 renames the field correctly, but the schema still treats it as a plain string instead of a URI, and Line 5960 still says “Song transcribed successfully.” Both should be updated so the rename is fully reflected in the docs.
Suggested fix
- "description": "Song transcribed successfully",
+ "description": "Audio transcribed successfully",
...
"audioUrl": {
"type": "string",
+ "format": "uri",
"description": "URL of the transcribed audio"
},🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 14864 - 14872, The schema rename
from songUrl to audioUrl is incomplete: update the OpenAPI schema for the
"audioUrl" property to declare it as a URI (keep "type": "string" but add
"format": "uri" and ensure the description references "audioUrl" as the URL of
the transcribed audio), and search the document for the legacy success message
"Song transcribed successfully." and change it to a matching phrase such as
"Audio transcribed successfully." Also sweep for any remaining occurrences of
the old property name "songUrl" and replace them with "audioUrl" (including
examples, response examples, and descriptions) so the rename is consistent
across the OpenAPI spec.
Applied to the split content.json (after #121 merged): 1. Image: add num_images, aspect_ratio, resolution; fix model name; add images array 2. Video: make image_url required; document model limitation 3. Edit: remove image_url (not implemented) 4. Transcribe: rename songUrl → audioUrl 5. Upscale: add upscale_factor and target_resolution Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
sweetmantech
force-pushed
the
fix/docs-match-content-api
branch
from
1ddbb1c to
dafa46e
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
api-reference/openapi/content.json (2)
2645-2672:⚠️ Potential issue | 🟠 Major
/api/content/videocontract is now internally contradictory around prompt mode.Lines 2645-2672 require
image_urland explicitly state text-only prompt mode is unsupported, but the endpoint/mode docs still describepromptas text-only generation (see Line 1344). This can lead consumers to construct impossible requests.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi/content.json` around lines 2645 - 2672, The OpenAPI contract for the POST /api/content/video is inconsistent: the schema currently marks "image_url" as required and its description states text-only prompt mode is unsupported, yet "mode" and the "prompt" property still imply text-only generation is allowed; update the schema to be consistent by either (A) allowing "image_url" to be optional when "mode" == "prompt" and adding conditional/oneOf validation and a clear "prompt" description that supports text-only generation, or (B) explicitly disallow "prompt" without "image_url" by changing the "prompt" description and "mode" enum docs to state that "prompt" mode requires an image and removing any text-only language; modify the properties "image_url", "prompt", and "mode" descriptions in the content.json to reflect the chosen behavior and ensure the note about the underlying model (fal-ai/veo3.1/fast/image-to-video) matches that decision.
2165-2177:⚠️ Potential issue | 🟠 MajorAdd schema constraint to enforce "video_url or audio_url required" rule.
The description documents this requirement, but the schema lacks structural enforcement—validators and SDK generators won't catch missing inputs. Use
anyOfwith required arrays to enforce validation at parse time.Proposed fix
"ContentCreateEditRequest": { "type": "object", "description": "Must provide at least one input (video_url or audio_url)", + "anyOf": [ + { "required": ["video_url"] }, + { "required": ["audio_url"] } + ], "properties": {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi/content.json` around lines 2165 - 2177, The schema currently defines properties "video_url" and "audio_url" but only documents the rule in the description; update the object schema to include an anyOf constraint that requires at least one of those properties (e.g., anyOf with [{"required":["video_url"]},{"required":["audio_url"]}]) so validators/SDKs enforce "video_url or audio_url required"; ensure the anyOf sits alongside the existing "type", "description", and "properties" entries for the object.
🧹 Nitpick comments (2)
api-reference/openapi/content.json (2)
2376-2379: Make the image model default machine-readable.Line 2378 encodes the default only in description text. Adding
defaultimproves SDK generation and schema-driven validation.Proposed fix
"model": { "type": "string", + "default": "fal-ai/nano-banana-2", "description": "fal.ai model ID. Defaults to fal-ai/nano-banana-2" }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi/content.json` around lines 2376 - 2379, The schema for the "model" property currently only documents the default in the description; add a machine-readable default by adding a "default": "fal-ai/nano-banana-2" entry to the "model" property object (the one with "type": "string" and "description") so SDKs and validators can pick up the default value.
2121-2124: Add URI format foraudioUrl.
audioUrlis documented as a URL, but Line 2121 currently only declarestype: string. Addformat: urifor stronger contract precision.Proposed fix
"audioUrl": { "type": "string", + "format": "uri", "description": "URL of the transcribed audio" }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi/content.json` around lines 2121 - 2124, The schema for the property "audioUrl" currently only has "type": "string"; update its schema to include "format": "uri" (i.e., add "format": "uri" alongside "type": "string") so the OpenAPI contract explicitly declares it as a URI; modify the "audioUrl" property definition in the JSON to include this format key and keep the existing description unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi/content.json`:
- Line 2166: The /api/content PATCH endpoint docs are inconsistent: the schema
only accepts video_url or audio_url but the endpoint description still says
“Accepts video, image, or audio input.” Update the description string for the
"/api/content" PATCH operation to remove image support (e.g., change to “Accepts
video or audio input” or similar), and verify any related examples, request
schema references, and the description field mentioning image are removed or
updated to reference only video_url and audio_url (search for the literal
description text and the request schema keys video_url/audio_url in
content.json).
---
Outside diff comments:
In `@api-reference/openapi/content.json`:
- Around line 2645-2672: The OpenAPI contract for the POST /api/content/video is
inconsistent: the schema currently marks "image_url" as required and its
description states text-only prompt mode is unsupported, yet "mode" and the
"prompt" property still imply text-only generation is allowed; update the schema
to be consistent by either (A) allowing "image_url" to be optional when "mode"
== "prompt" and adding conditional/oneOf validation and a clear "prompt"
description that supports text-only generation, or (B) explicitly disallow
"prompt" without "image_url" by changing the "prompt" description and "mode"
enum docs to state that "prompt" mode requires an image and removing any
text-only language; modify the properties "image_url", "prompt", and "mode"
descriptions in the content.json to reflect the chosen behavior and ensure the
note about the underlying model (fal-ai/veo3.1/fast/image-to-video) matches that
decision.
- Around line 2165-2177: The schema currently defines properties "video_url" and
"audio_url" but only documents the rule in the description; update the object
schema to include an anyOf constraint that requires at least one of those
properties (e.g., anyOf with
[{"required":["video_url"]},{"required":["audio_url"]}]) so validators/SDKs
enforce "video_url or audio_url required"; ensure the anyOf sits alongside the
existing "type", "description", and "properties" entries for the object.
---
Nitpick comments:
In `@api-reference/openapi/content.json`:
- Around line 2376-2379: The schema for the "model" property currently only
documents the default in the description; add a machine-readable default by
adding a "default": "fal-ai/nano-banana-2" entry to the "model" property object
(the one with "type": "string" and "description") so SDKs and validators can
pick up the default value.
- Around line 2121-2124: The schema for the property "audioUrl" currently only
has "type": "string"; update its schema to include "format": "uri" (i.e., add
"format": "uri" alongside "type": "string") so the OpenAPI contract explicitly
declares it as a URI; modify the "audioUrl" property definition in the JSON to
include this format key and keep the existing description unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 3c471670-f7cc-4898-9cbe-c9aa6f525a29
📒 Files selected for processing (1)
api-reference/openapi/content.json
Collaborator
Author
Visual Verification — All 5 Changes ConfirmedTested each changed page on localhost:3000 with Chrome DevTools:
🤖 Generated with Claude Code |
…nce) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
… examples 1. Video response: add mode field (prompt/animate/reference/extend/first-last/lipsync) 2. Transcribe request: add language, chunk_level, diarize params 3. Caption response: fix color examples to match API (white/black, maxFontSize 42) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/content.json">
<violation number="1" location="api-reference/openapi/content.json:2106">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
Three new transcribe request parameters (`language`, `chunk_level`, `diarize`) are added but not listed among the PR's verified changes. The PR carefully enumerates all 5 tested discrepancies, and change #4 for transcribe only covers renaming `songUrl` → `audioUrl` in the response. Undocumented spec additions in a PR titled "align OpenAPI spec with content API implementation" risk documenting parameters that don't actually exist in the API, misleading consumers.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| "minItems": 1, | ||
| "description": "Audio file URLs to transcribe" | ||
| }, | ||
| "language": { |
There was a problem hiding this comment.
P1: Custom agent: Flag AI Slop and Fabricated Changes
Three new transcribe request parameters (language, chunk_level, diarize) are added but not listed among the PR's verified changes. The PR carefully enumerates all 5 tested discrepancies, and change #4 for transcribe only covers renaming songUrl → audioUrl in the response. Undocumented spec additions in a PR titled "align OpenAPI spec with content API implementation" risk documenting parameters that don't actually exist in the API, misleading consumers.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/content.json, line 2106:
<comment>Three new transcribe request parameters (`language`, `chunk_level`, `diarize`) are added but not listed among the PR's verified changes. The PR carefully enumerates all 5 tested discrepancies, and change #4 for transcribe only covers renaming `songUrl` → `audioUrl` in the response. Undocumented spec additions in a PR titled "align OpenAPI spec with content API implementation" risk documenting parameters that don't actually exist in the API, misleading consumers.</comment>
<file context>
@@ -2103,6 +2103,26 @@
"minItems": 1,
"description": "Audio file URLs to transcribe"
},
+ "language": {
+ "type": "string",
+ "default": "en",
</file context>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Changes
POST /api/content/imagenum_images,aspect_ratio,resolutionparams; fix default model tofal-ai/nano-banana-2; addimagesarray to responsePOST /api/content/videoimage_urlrequired; document that text-only prompt mode is not supportedPATCH /api/contentimage_urlparam (API only acceptsvideo_urlandaudio_url)POST /api/content/transcribesongUrl→audioUrlPOST /api/content/upscaleupscale_factorandtarget_resolutionparamsTest plan
🤖 Generated with Claude Code
Summary by cubic
Aligns the OpenAPI docs with the Content API to fix spec mismatches and add missing fields. Clients now see the right params, required fields, defaults, responses, and examples.
fal-ai/nano-banana-2; add images array in responsefal-ai/veo3.1/fast/image-to-video); add response field mode (prompt/animate/reference/extend/first-last/lipsync)Written for commit e65c350. Summary will update on new commits.
Summary by CodeRabbit
New Features
API Changes
songUrltoaudioUrl